<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!-- Copyright 1997 The Open Group, All Rights Reserved -->
<title>locale</title>
</head><body bgcolor=white>
<center>
<font size=2>
The Single UNIX &reg; Specification, Version 2<br>
Copyright &copy; 1997 The Open Group

</font></center><hr size=2 noshade>
<h4><a name = "tag_001_014_1175">&nbsp;</a>NAME</h4><blockquote>
locale - get locale-specific information
</blockquote><h4><a name = "tag_001_014_1176">&nbsp;</a>SYNOPSIS</h4><blockquote>
<pre><code>

locale <b>[</b> -a| -m<b>]</b>

locale <b>[</b>-ck<b>] </b><i>name</i>...
</code>
</pre>
</blockquote><h4><a name = "tag_001_014_1177">&nbsp;</a>DESCRIPTION</h4><blockquote>
The
<i>locale</i>
utility writes information about the current locale environment,
or all public locales, to the standard output.
For the purposes of this section, a
<i>public locale</i>
is one provided by the implementation that is accessible
to the application.
<p>
When
<i>locale</i>
is invoked without any arguments, it summarises the
current locale environment for each locale category as determined
by the settings of the environment variables defined in
the <b>XBD</b> specification, <a href="../xbd/locale.html"><b>Locale</b>&nbsp;</a> .
<p>
When invoked with operands,
it writes values that have been
assigned to the keywords in the
locale categories, as follows:
<ul>
<p>
<li>
Specifying a keyword name selects the named keyword and the category
containing that keyword.
<p>
<li>
Specifying a category name selects the named category
and all keywords in that category.
<p>
</ul>
</blockquote><h4><a name = "tag_001_014_1178">&nbsp;</a>OPTIONS</h4><blockquote>
The
<i>locale</i>
utility supports the <b>XBD</b> specification, <a href="../xbd/utilconv.html#usg"><b>Utility Syntax Guidelines</b>&nbsp;</a> .
<p>
The following options are supported:
<dl compact>

<dt><b>-a</b>
<dd>Write information about all available public locales.
The available locales include
<b>POSIX</b>,
representing the POSIX locale.
The manner in which the implementation determines what other
locales are available
is implementation-dependent.

<dt><b>-c</b>
<dd>Write the names of selected locale categories;
see the STDOUT section.
The
<b>-c</b>
option increases readability when more than one
category is selected (for example, via more than one keyword name
or via a category name).
It is valid both with and without the
<b>-k</b>
option.

<dt><b>-k</b>
<dd>Write the names and values of selected keywords.
The implementation may omit values for some keywords;
see the OPERANDS section.

<dt><b>-m</b>
<dd>Write names of available charmaps;
see
the <b>XBD</b> specification, <a href="../xbd/charset.html#tag_001_001"><b>Portable Character Set</b>&nbsp;</a> .

</dl>
</blockquote><h4><a name = "tag_001_014_1179">&nbsp;</a>OPERANDS</h4><blockquote>
The following operand is supported:
<dl compact>

<dt><i>name</i><dd>The name of a locale category as defined in
the <b>XBD</b> specification, <a href="../xbd/locale.html"><b>Locale</b>&nbsp;</a> ,
the name of a keyword in a locale category,
or the reserved name
<b>charmap</b>.
The named category or keyword will be selected for output.
If a single
<i>name</i>
represents both a locale category name and a keyword name
in the current locale, the results are unspecified.
Otherwise, both category and keyword names can be
specified as
<i>name</i>
operands, in any sequence.
It is implementation-dependent whether any keyword values
are written for the categories LC_CTYPE and LC_COLLATE.

</dl>
</blockquote><h4><a name = "tag_001_014_1180">&nbsp;</a>STDIN</h4><blockquote>
Not used.
</blockquote><h4><a name = "tag_001_014_1181">&nbsp;</a>INPUT FILES</h4><blockquote>
None.
</blockquote><h4><a name = "tag_001_014_1182">&nbsp;</a>ENVIRONMENT VARIABLES</h4><blockquote>
The following environment variables affect the execution of
<i>locale</i>:
<dl compact>

<dt><i>LANG</i><dd>Provide a default value for the internationalisation variables
that are unset or null.
If
<i>LANG</i>
is unset or null, the corresponding value from the
implementation-dependent default locale will be used.
If any of the internationalisation variables contains an invalid setting, the
utility will behave as if none of the variables had been defined.

<dt><i>LC_ALL</i><dd>
If set to a non-empty string value,
override the values of all the other internationalisation variables.

<dt><i>LC_CTYPE</i><dd>
Determine the
locale for the interpretation of sequences of bytes of text data as
characters (for example, single- as opposed to multi-byte characters
in arguments and input files).

<dt><i>LC_MESSAGES</i><dd>
Determine the locale that should be used to affect
the format and contents of diagnostic
messages written to standard error.

<dt><i>NLSPATH</i><dd>
Determine the location of message catalogues
for the processing of
<i>LC_MESSAGES .
</i>
</dl>
<p>
The
<i>LANG ,
</i><i>LC_*</i>
and
<i>NLSPATH</i>
environment variables must specify the current locale environment
to be written out; they will be used if the
<b>-a</b>
option is not specified.
</blockquote><h4><a name = "tag_001_014_1183">&nbsp;</a>ASYNCHRONOUS EVENTS</h4><blockquote>
Default.
</blockquote><h4><a name = "tag_001_014_1184">&nbsp;</a>STDOUT</h4><blockquote>
If
<i>locale</i>
is invoked without any options or operands, the names
and values of the
<i>LANG</i>
and
<i>LC_*</i>
environment variables described in this specification
will be written to the standard output,
one variable per line,
with
<i>LANG</i>
first,
and each line using the following format.
Only those variables set in the environment and not overridden by
<i>LC_ALL</i>
will be written using this format:
<p><code>
<tt>"%s=%s\n"</tt>, &lt;<i>variable_name</i>&gt;,
&lt;<i>value</i>&gt;
</code>
<p>
The names of those
<i>LC_*</i>
variables associated with locale categories defined in this specification
that are not set in the environment or are overridden by
<i>LC_ALL</i>
will be written in the following format:
<p><code>
<tt>"%s=\"%s\"\n"</tt>, &lt;<i>variable_name</i>&gt;,
&lt;<i>implied&nbsp;value</i>&gt;
</code>
<p>
The
&lt;<i>implied&nbsp;value</i>&gt;
is the name of the locale that has been
selected for that category by the implementation, based on the values in
<i>LANG</i>
and
<i>LC_ALL ,
</i>as described in
the <b>XBD</b> specification, <a href="../xbd/envvar.html"><b>Environment Variables</b>&nbsp;</a> .
<p>
The
&lt;<i>value</i>&gt;
and
&lt;<i>implied&nbsp;value</i>&gt;
shown above
will be properly quoted for possible later reentry to the shell.
The
&lt;<i>value</i>&gt;
will not be quoted using double-quotes (so that it can be distinguished
by the user from the
&lt;<i>implied&nbsp;value</i>&gt;
case, which always requires double-quotes).
<p>
The
<i>LC_ALL</i>
variable will be written last,
using the first format shown above.
If it is not set, it will be written as:
<pre>
<code>
"LC_ALL=\n"
</code>
</pre>
<p>
If any arguments are specified:
<ol>
<p>
<li>
If the
<b>-a</b>
option is specified, the
names of all the public locales will be written,
each in the following format:
<p><code>
<tt>"%s\n"</tt>, &lt;<i>locale&nbsp;name</i>&gt;
</code>
<p>
<li>
If the
<b>-c</b>
option is specified, the names of all selected categories
will be written, each in the following format:
<p><code>
<tt>"%s\n"</tt>, &lt;<i>category&nbsp;name</i>&gt;
</code>
<p>
If keywords are also selected for writing (see following items),
the category name output will precede the keyword output
for that category.
<p>
If the
<b>-c</b>
option is not specified, the names of the categories
will not be written; only the keywords, as selected by the
<i>name</i>
operand, will be written.
<p>
<li>
If the
<b>-k</b>
option is specified, the names and values
of selected keywords will be written.
If a value is non-numeric,
it will be written in the following format:
<p><code>
"%s=\"%s\"\n",
&lt;<i>keyword&nbsp;name</i>&gt;,
&lt;<i>keyword&nbsp;value</i>&gt;
</code>
<p>
If the keyword was
<b>charmap</b>,
the name of the charmap (if any) that was specified via the
<i><a href="localedef.html">localedef</a></i>
<b>-f</b>
option when the locale was created will be written, with the word
<b>charmap</b>
as
&lt;<i>keyword name</i>&gt;.
<p>
If a value is numeric,
it will be written in one of the following formats:
<p><code>
<tt>"%s=%d\n"</tt>, &lt;<i>keyword&nbsp;name</i>&gt;,
&lt;<i>keyword&nbsp;value</i>&gt;
</code>
<p><code>
<pre>
<tt>"%s=%c%o\n"</tt>, &lt;<i>keyword&nbsp;name</i>&gt;,
&lt;<i>escape&nbsp;character</i>&gt;,
&lt;<i>keyword&nbsp;value</i>&gt;
</pre>
</code>
<p><code>
<pre>
<tt>"%s=%cx%x\n"</tt>, &lt;<i>keyword&nbsp;name</i>&gt;,
&lt;<i>escape&nbsp;character</i>&gt;,
&lt;<i>keyword&nbsp;value</i>&gt;
</pre>
</code>
where the
&lt;<i>escape&nbsp;character</i>&gt;
is that identified by the
<b>escape_char</b>
keyword in the current locale; see
the <b>XBD</b> specification, <a href="../xbd/locale.html#tag_005_003"><b>Locale Definitions</b>&nbsp;</a> .
<p>
Compound keyword values (list entries) will be separated
in the output by semicolons.
When included in keyword values, the semicolon,
the double-quote, the backslash and any control character
will be preceded (escaped) with the escape character.
<p>
<li>
If the
<b>-k</b>
option is not specified,
selected keyword values will be written,
each in the following format:
<p><code>
<tt>"%s\n"</tt>, &lt;<i>keyword&nbsp;value</i>&gt;
</code>
<p>
If the keyword was
<b>charmap</b>,
the name of the charmap (if any) that was specified via the
<i><a href="localedef.html">localedef</a></i>
<b>-f</b>
option when the locale was created will be written.
<p>
<li>
If the
<b>-m</b>
option is specified, then a list of all available
charmaps will be written, each in the format:
<p><code>
<pre>
<tt>"%s\n"</tt>, &lt;<i>charmap</i>&gt;
</pre>
</code>
where
&lt;<i>charmap</i>&gt;
is in a format suitable for use as the option-argument to the
<i><a href="localedef.html">localedef</a></i>
<b>-f</b>
option.
<p>
</ol>
</blockquote><h4><a name = "tag_001_014_1185">&nbsp;</a>STDERR</h4><blockquote>
Used only for diagnostic messages.
</blockquote><h4><a name = "tag_001_014_1186">&nbsp;</a>OUTPUT FILES</h4><blockquote>
None.
</blockquote><h4><a name = "tag_001_014_1187">&nbsp;</a>EXTENDED DESCRIPTION</h4><blockquote>
None.
</blockquote><h4><a name = "tag_001_014_1188">&nbsp;</a>EXIT STATUS</h4><blockquote>
The following exit values are returned:
<dl compact>

<dt>0<dd>All the requested information was found and output successfully.

<dt>&gt;0<dd>An error occurred.

</dl>
</blockquote><h4><a name = "tag_001_014_1189">&nbsp;</a>CONSEQUENCES OF ERRORS</h4><blockquote>
Default.
</blockquote><h4><a name = "tag_001_014_1190">&nbsp;</a>APPLICATION USAGE</h4><blockquote>
If the
<i>LANG</i>
environment variable is not set or set to an empty value, or
one of the
<i>LC_*</i>
environment variables is set to an unrecognised value,
the actual locales assumed (if any) are implementation-dependent as
described in
the <b>XBD</b> specification, <a href="../xbd/envvar.html"><b>Environment Variables</b>&nbsp;</a> .
<p>
Implementations are not required to write out the actual values
for keywords in the categories LC_CTYPE and LC_COLLATE; however,
they must write out the categories (allowing an application to determine,
for example, which character classes are available).
</blockquote><h4><a name = "tag_001_014_1191">&nbsp;</a>EXAMPLES</h4><blockquote>
In the following examples, the assumption is that locale environment
variables are set as follows:
<pre>
<code>
LANG=locale_x
LC_COLLATE=locale_y
</code>
</pre>
<p>
The command:
<pre>
<code>
locale
</code>
</pre>
would result in the following output:
<pre>
<code>
LANG=locale_x
LC_CTYPE="locale_x"
LC_COLLATE=locale_y
LC_TIME="locale_x"
LC_NUMERIC="locale_x"
LC_MONETARY="locale_x"
LC_MESSAGES="locale_x"
LC_ALL=
</code>
</pre>
<p>
The order of presentation of the categories
is not specified by this specification.
<p>
The command:
<pre>
<code>
LC_ALL=POSIX locale -ck decimal_point
</code>
</pre>
would produce:
<pre>
<code>
LC_NUMERIC
decimal_point="."
</code>
</pre>
<p>
The following command shows an application of
<i>locale</i>
to determine whether a user-supplied response is affirmative:
<pre>
<code>
if printf "%s\n" "$response" | grep -Eq "$(locale yesexpr)"
then
    affirmative processing goes here
else
    non-affirmative processing goes here
fi
</code>
</pre>
</blockquote><h4><a name = "tag_001_014_1192">&nbsp;</a>FUTURE DIRECTIONS</h4><blockquote>
The IEEE PASC 1003.2 Interpretations Committee has forwarded concerns about
parts of this interface definition to the IEEE PASC Shell and Utilities Working Group
which is identifying the corrections.
A future revision of this specification will align with
IEEE Std. 1003.2b when finalised.
</blockquote><h4><a name = "tag_001_014_1193">&nbsp;</a>SEE ALSO</h4><blockquote>
<i><a href="localedef.html">localedef</a></i>,
the <b>XBD</b> specification, <a href="../xbd/locale.html#tag_005_003"><b>Locale Definitions</b>&nbsp;</a> .
</blockquote><hr size=2 noshade>
<center><font size=2>
UNIX &reg; is a registered Trademark of The Open Group.<br>
Copyright &copy; 1997 The Open Group
<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]

</font></center><hr size=2 noshade>
</body></html>
